Summary

• write CPS, extended CPS, and PUF-imputed retirement contribution source values to desired pre-limit variables for 401(k), IRA, and self-employed pension contributions
• keep statutory contribution limits out of us-data post-processing; PolicyEngine-US now applies those limits through the plain contribution variables
• target retirement calibration/loss/national-target parity surfaces on the plain PolicyEngine-US contribution outputs, including self_employed_pension_contributions
• update the changelog and focused tests for the desired-input/plain-output architecture
• refresh against current main and keep its newer temporary policyengine-us Git pin

Dependency note

PolicyEngine-US includes the desired retirement contribution inputs and plain contribution formulas in merged code, but PyPI publication is currently blocked by the policyengine-us project-size limit. This PR therefore follows the precedent from #987 and temporarily pins policyengine-us to the exact upstream Git commit currently used by main (1da04a64dcdce26834b063d68daa835765a5d8ed, version 1.706.14). The dependency guard allows this only while the locked version is newer than the latest PyPI release and warns to switch back to an exact PyPI pin once publication is restored.

Supersedes

• Supersedes Write 401(k) deferrals to the new *_desired inputs #1122, which was the earlier 401(k)-only version.

Tests

• uv run ruff check .github/scripts/check_policyengine_us_dependency.py policyengine_us_data/calibration/puf_impute.py policyengine_us_data/datasets/cps/cps.py policyengine_us_data/datasets/cps/extended_cps.py policyengine_us_data/datasets/puf/puf.py policyengine_us_data/db/etl_national_targets.py policyengine_us_data/storage/calibration_targets/soi_metadata.py policyengine_us_data/utils/loss.py policyengine_us_data/utils/national_target_parity.py tests/unit/calibration/test_calibration_puf_impute.py tests/unit/calibration/test_retirement_imputation.py tests/unit/datasets/test_cps_income_variables.py tests/unit/test_extended_cps.py tests/unit/test_income_target_mappings.py
• env UV_FROZEN=0 uv lock --locked
• uv run python .github/scripts/check_policyengine_us_dependency.py --mode fail
• variable-shape smoke check: desired retirement variables are inputs; plain contribution variables are formulas, using policyengine-us 1.706.14
• uv run pytest tests/unit/datasets/test_cps_income_variables.py tests/unit/test_extended_cps.py tests/unit/calibration/test_retirement_imputation.py tests/unit/calibration/test_calibration_puf_impute.py tests/unit/test_income_target_mappings.py -q — 148 passed